'\" te
.\"  Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PAM_KRB5_MIGRATE 7 "August 19, 2023"
.SH NAME
pam_krb5_migrate \- authentication PAM module for the KerberosV5 auto-migration
of users feature
.SH SYNOPSIS
.nf
\fBpam_krb5_migrate.so.1\fR
.fi

.SH DESCRIPTION
The KerberosV5 auto-migrate service module for \fBPAM\fR,
\fBpam_krb5_migrate.so.1\fR, provides functionality for
the PAM authentication component. The service module helps in the automatic
migration of \fBPAM_USER\fR to the client's local Kerberos realm, using
\fBPAM_AUTHTOK\fR (the PAM authentication token associated with \fBPAM_USER\fR)
as the new Kerberos principal's password.
.SS "KerberosV5 Auto-migrate Authentication Module"
The KerberosV5 auto-migrate authentication component provides the
\fBpam_sm_authenticate\fR(3PAM) function to migrate a user who does not have a
corresponding \fBkrb5\fR principal account to the default Kerberos realm of the
client.
.sp
.LP
\fBpam_sm_authenticate\fR(3PAM) uses a host-based client service principal,
present in the local \fBkeytab\fR (\fB/etc/krb5/krb5.keytab\fR) to authenticate
to \fBkadmind\fR(8) (defaults to the \fBhost/nodename.fqdn\fR service
principal), for the principal creation operation. Also, for successful creation
of the \fBkrb5\fR user principal account, the host-based client service
principal being used needs to be assigned the appropriate privilege on the
master KDC's \fBkadm5.acl\fR(5) file. \fBkadmind\fR(8) checks for the
appropriate privilege and validates the user password using PAM by calling
\fBpam_authenticate\fR(3PAM) and \fBpam_acct_mgmt\fR(3PAM) for the
\fBk5migrate\fR service.
.sp
.LP
If migration of the user to the KerberosV5 infrastructure is successful, the
module will inform users about it by means of a \fBPAM_TEXT_INFO\fR message,
unless instructed otherwise by the presence of the \fBquiet\fR option.
.sp
.LP
The authentication component always returns \fBPAM_IGNORE\fR and is meant to be
stacked in \fBpam.conf\fR with a requirement that it be listed below
\fBpam_authtok_get\fR(7) in the authentication stack.
Also, if \fBpam_krb5_migrate\fR
is used in the authentication stack of a particular service, it is mandatory
that \fBpam_krb5\fR(7) be listed in the PAM account stack of that service for
proper operation (see EXAMPLES).
.SH OPTIONS
The following options can be passed to the KerberosV5 auto-migrate
authentication module:
.sp
.ne 2
.na
\fB\fBdebug\fR\fR
.ad
.sp .6
.RS 4n
Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
.RE

.sp
.ne 2
.na
\fB\fBclient_service=\fR\fI<service name>\fR\fR
.ad
.sp .6
.RS 4n
Name of the service used to authenticate to \fBkadmind\fR(8) defaults to
\fBhost\fR. This means that the module uses \fBhost/\fR\fI<nodename.fqdn>\fR as
its client service principal name, KerberosV5 user principal creation operation
or \fI<service>\fR/\fI<nodename.fqdn>\fR if this option is provided.
.RE

.sp
.ne 2
.na
\fB\fBquiet\fR\fR
.ad
.sp .6
.RS 4n
Do not explain KerberosV5 migration to the user.
.sp
This has the same effect as passing the \fBPAM_SILENT\fR flag to
\fBpam_sm_authenticate\fR(3PAM) and is useful where applications cannot handle
\fBPAM_TEXT_INFO\fR messages.
.sp
If not set, the authentication component will issue a \fBPAM_TEXT_INFO\fR
message after creation of the Kerberos V5 principal, indicating that it has
done so.
.RE

.sp
.ne 2
.na
\fB\fBexpire_pw\fR\fR
.ad
.sp .6
.RS 4n
Causes the creation of KerberosV5 user principals with password expiration set
to \fBnow\fR (current time).
.RE

.SH EXAMPLES
\fBExample 1 \fRSample Entries from \fBpam.conf\fR
.sp
.LP
The following entries from \fBpam.conf\fR(5) demonstrate the use of the
\fBpam_krb5_migrate.so.1\fR module:

.sp
.in +2
.nf
login       auth requisite          pam_authtok_get.so.1
login       auth required           pam_dhkeys.so.1
login       auth required           pam_unix_cred.so.1
login       auth sufficient         pam_krb5.so.1
login       auth requisite          pam_unix_auth.so.1
login       auth optional           pam_krb5_migrate.so.1 expire_pw
login       auth required           pam_dial_auth.so.1

other   account requisite       pam_roles.so.1
other   account required        pam_krb5.so.1
other   account required        pam_unix_account.so.1
.fi
.in -2

.sp
.LP
The \fBpam_krb5_migrate\fR module can generally be present on the
authentication stack of any service where the application calls
\fBpam_sm_authenticate\fR(3PAM) and an authentication token (in the preceding
example, the authentication token would be the user's Unix password) is
available for use as a Kerberos V5 password.

.LP
\fBExample 2 \fRSample Entries from \fBkadm5.acl\fR
.sp
.LP
The following entries from \fBkadm5.acl\fR(5) permit or deny privileges to the
host client service principal:

.sp
.in +2
.nf
host/*@EXAMPLE.COM U root
host/*@EXAMPLE.COM ui *
.fi
.in -2

.sp
.LP
The preceding entries permit the \fBpam_krb5_migrate\fR \fBadd\fR privilege to
the host client service principal of any machine in the \fBEXAMPLE.COM\fR
KerberosV5 realm, but denies the \fBadd\fR privilege to all host service
principals for addition of the root user account.

.LP
\fBExample 3 \fRSample Entries in \fBpam.conf\fR of the Master KDC
.sp
.LP
The entries below enable \fBkadmind\fR(8) on the master KDC to use the
\fBk5migrate\fR PAM service in order to validate Unix user passwords for
accounts that require migration to the Kerberos realm.

.sp
.in +2
.nf
k5migrate        auth    required        pam_unix_auth.so.1
k5migrate        account required        pam_unix_account.so.1
.fi
.in -2

.SH ATTRIBUTES
See \fBattributes\fR(7) for a description of the following attribute:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.BR syslog (3C),
.BR pam_acct_mgmt (3PAM),
.BR pam_authenticate (3PAM),
.BR pam_sm_authenticate (3PAM),
.BR kadm5.acl (5),
.BR pam.conf (5),
.BR attributes (7),
.BR pam_authtok_get (7),
.BR pam_krb5 (7),
.BR kadmind (8)
